Cream of the Crop 1

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / EVISION1.ARJ / USERDOC.TXT < prev

Wrap

Text File | 1992-05-19 | 131KB | 4,131 lines

┌─────────────────────────────────────────────────────────────────────┐ │ │ │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │ │ ▒▒█████████▒▒█████████▒▒█████████▒▒██▒▒▒▒▒▒██▒▒▒▒┌────────────┐▒▒ │ │ ▒▒██ ▒██ ██ ▒██ ▒██ ▒▒▒▒▒██ ▒▒▒│ │ ▒ │ │ ▒▒██ ▒▒▒▒▒▒▒▒██ ▒▒▒▒██ ▒██ ▒▒▒▒▒▒▒▒██ ▒▒▒▒▒██ ▒▒▒│ █ █▀█ │ ▒ │ │ ▒▒█████████▒▒█████████ ▒█████████▒▒██████████ ▒▒▒│ █ ▄ █▄█ │ ▒ │ │ ▒▒██ ▒██ ██ ▒▒ ██ ▒▒ ██ ▒▒▒│ │ ▒ │ │ ▒▒██ ▒▒▒▒▒▒▒▒██ ▒▒▒▒██ ▒▒▒▒▒▒▒▒██ ▒▒▒▒▒██ ▒▒▒▒▒▒▒├────────────┤ ▒ │ │ ▒▒█████████▒▒██ ▒▒▒▒██ ▒█████████ ▒▒▒▒▒██ ▒▒▒▒▒▒▒│ User Guide │ ▒ │ │ ▒▒▒ ▒▒ ▒▒▒▒▒ ▒▒ ▒▒▒▒▒▒ ▒▒▒▒▒▒▒└────────────┘ ▒ │ │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒ │ │ ▒▒██▒▒▒▒▒██▒▒██▒▒█████████▒▒██▒▒█████████▒▒█████████▒▒▒▒▒▒▒▒▒▒▒▒▒ │ │ ▒▒██ ▒▒▒▒██ ▒██ ▒██ ▒██ ▒██ ██ ▒██ ██ ▒▒▒▒▒▒▒▒▒▒▒▒ │ │ ▒▒██ ▒▒▒▒██ ▒██ ▒██ ▒▒▒▒▒▒▒▒██ ▒██ ▒▒▒▒██ ▒██ ▒▒▒▒██ ▒▒▒▒▒▒▒▒▒▒▒▒ │ │ ▒▒██ ▒▒▒▒██ ▒██ ▒█████████▒▒██ ▒██ ▒▒▒▒██ ▒██ ▒▒▒▒██ ▒▒▒▒▒▒▒▒▒▒▒▒ │ │ ▒▒██ ▒▒▒▒██ ▒██ ▒▒ ██ ▒██ ▒██ ▒▒▒▒██ ▒██ ▒▒▒▒██ ▒▒▒▒▒▒▒▒▒▒▒▒ │ │ ▒▒▒██ ▒▒██ ▒▒██ ▒▒▒▒▒▒▒▒██ ▒██ ▒██ ▒▒▒▒██ ▒██ ▒▒▒▒██ ▒▒▒▒▒▒▒▒▒▒▒▒ │ │ ▒▒▒▒█████ ▒▒▒██ ▒█████████ ▒██ ▒█████████ ▒██ ▒▒▒▒██ ▒▒▒▒▒▒▒▒▒▒▒▒ │ │ ▒▒▒▒▒ ▒▒▒▒ ▒▒ ▒▒ ▒▒ ▒▒ ▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒ │ │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │ │ │ │ The easy to use, reliable and powerful library for a textmode │ │ based user interface. │ │ │ │ This manual may be freely distributed in its original form. │ │ Modifications of any kind are prohibited. │ │ │ │ This manual and software are made available without warranties. │ │ TNG SOFT nor the author shall be held liable to the user or any │ │ other person or entity with respect to any liability, loss, or │ │ damage caused or alleged to be caused directly or indirectly by │ │ this manual or software. │ │ │ │ This software is shareware, and must be registered. │ │ │ │ This library is the property of the author. │ │ You are granted the rights to use only. │ │ │ │ EasyVision is a registered trademark of TNG SOFT. │ │ │ │ The original manual and software may be obtained from │ │ │ │ STARFLEET COMMAND BBS │ │ (418) 525-6899/4740/6803 │ │ FidoNet: 1:240/1701 │ │ F'req magic name > EVISION │ │ │ │ │ │ ▀█▀ █▀█ █▀▀ █▀▀ █▀█ █▀▀ ▀█▀ │ │ █ █ █ █▄█ ▄▄█ █▄█ █▀ █ The Next Generation Software │ │ │ └─────────────────────────────────────────────────────────────────────┘ EasyVision 1.0 User's Guide Page 2 Chapter 1: Overview ..................................... 7 Why EasyVision .......................... 7 What is EasyVision ...................... 7 Current version ......................... 8 A word about registration ............... 8 What's next ? ........................... 9 Chapter 2: Getting started .............................. 10 Library specifics ....................... 10 Installation ............................ 10 How to use this library ................. 11 How to use this document ................ 11 Chapter 3: Using EasyVision's functions ................. 13 assert .................................. 14 getkey .................................. 15 getheap ................................. 17 freeheap ................................ 17 hstrlen ................................. 18 hstrcpy ................................. 18 savevideo ............................... 19 restorevideo ............................ 19 savecursor .............................. 20 restorecursor ........................... 20 Chapter 4: Using EasyVision's classes ................... 21 Chapter 5: EasyVision's TDesktop class .................. 22 settextmode ............................. 23 setdeskcolors ........................... 23 settexture .............................. 24 settitle ................................ 24 open .................................... 25 close ................................... 25 insert .................................. 26 refresh ................................. 26 Chapter 6: EasyVision's TStatusline class ............... 27 setleftcolors ........................... 28 setrightcolors .......................... 28 displayleft ............................. 29 displayright ............................ 29 refresh ................................. 30 EasyVision 1.0 User's Guide Page 3 Chapter 7: EasyVision's TMenubar class .................. 31 setcolors ............................... 32 sethelp ................................. 33 setslptr ................................ 33 addmenu ................................. 34 additem ................................. 35 trough .................................. 36 itemavail ............................... 36 refresh ................................. 37 Chapter 8: EasyVision's TWindow class ................... 38 wingetscreenheight ...................... 39 wingetscreenwidth ....................... 39 winsetpos ............................... 40 wingetrow ............................... 41 wingetcol ............................... 41 winsetsize .............................. 42 wingetheight ............................ 42 wingetwidth ............................. 42 winsetcolors ............................ 43 winsettitle ............................. 43 winsethelp .............................. 44 winsetslptr ............................. 44 winopen ................................. 45 winclose ................................ 45 winclear ................................ 46 winwrite ................................ 47 winswrite ............................... 49 wintext ................................. 50 wintextfile ............................. 51 winmove ................................. 52 winscroll ............................... 52 wininput ................................ 53 fieldsetlengths ......................... 54 fieldsetcolors .......................... 54 fieldsetftr ............................. 55 fieldsetattrib .......................... 55 fieldcreate ............................. 56 fieldinput .............................. 57 fieldsetasw ............................. 58 fieldgetasw ............................. 58 buttonsetcolors ......................... 59 buttoncreate ............................ 60 buttonpush .............................. 62 buttoninput ............................. 63 buttonsetavail .......................... 64 EasyVision 1.0 User's Guide Page 4 Chapter 9: EasyVision's Demo Program .................... 65 The demo program ........................ 65 Chapter 10: Things you should not do ..................... 66 Appendix A: Extended keycodes ............................ 67 Appendix B: Color codes and Symbolic constants ........... 68 Appendix C: Trademarks ................................... 69 Appendix D: Common Questions and Answers ................. 70 EasyVision 1.0 User's Guide Page 5 This page intentionally left blank EasyVision 1.0 User's Guide Page 6 This page intentionally left blank EasyVision 1.0 User's Guide Page 7 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 1 Overview ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Welcome to EasyVision 1.0 ! This C++ library provides an easy to use, reliable and powerful textmode based user interface. Why EasyVision ? ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ After looking at some shareware and commercial user interface packages, and reading comments about them from a lot of C and C++ programmers, it was clear that something was missing. When people talked about TURBO VISION from BORLAND, it was their opinion that it was too difficult to use. In my own opinion, I think that TURBO VISION is one of the greatest work of software engineering around. It is the most powerful and professional user interface in existence. It is so well implemented and thought out that it is the standard in textmode interfaces that everyone is following, including EasyVison ! (Hope they don't sue me...) But, it is so big that it is a language in itself, and that is what makes people afraid of using it ! On the other hand, there are those shareware libraries. Some of them are extraordinarily well done, but are still much to big. I'm thinking about CXL right now. Others are to small and to unreliable to develop serious software. So, what's a C++ programmer to do ? Maybe just what I did, and write all of his interface himself. But what a waste if I'm the only one using it ! Why not make it available to everyone ? Well, that's what EasyVision is all about ! What is EasyVision ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ EasyVision is a textmode based, windowed user interface. It provides a DESKTOP, a STATUSLINE, a MENUBAR, WINDOWS, CONTEXT SENSITIVE ONLINE HELP, and much much more... EasyVision was created with 2 important priorities. EasyVision 1.0 User's Guide Page 8 First, it should be EASY to learn and EASY to use. Provide only the big, important functions to the user. A user doesn't need a library function if he can write it himself in less than 25 lines of code. But make sure that those big functions are REALLY powerful and produce professional looking results ! This library hasn't been written to provide every fonctions needed to developpe full featured word processors or the likes. It is there to give you a strong and reliable skeleton for your programs. It is up to you to come up with the 'meat'. Second, those functions should be totally bug free and crash proof. EasyVision should validate all parameters to make sure nothing wrong can happen. Don't rely on the good will of the programmer to check out is code for out of range or non-initialised parameters. That was what EasyVision was suppose to be. Well, EasyVision is still better than that ! At this point, if you haven't already done so, you should run the demonstation program 'EVISION.EXE' to see the results of about 200 lines of C++ codes that uses the EasyVision library... If you find the results interesting, it is up to you to go on. All functions and classes are FULLY documented in the following pages. The source code of the demonstration program is also included (and commented) in the archive. It provides you with 'real' examples of how to use this library. Current Version ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The complete history of EasyVision can be found in the HISTORY.TXT file, included in the archive. A word about registration ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ EasyVision 1.0 is made available under the shareware concept. This means that after an evaluation period of 30 days, you should register this software with its author. Furthermore, if you use this software to create your own shareware software, YOU MUST REGISTER EASYVISION. Registration grants you a life-time license to use this software, and all following versions or updates. EasyVision is NOT crippled in any way. There is absolutly no differences between the registered or unregistered version. EasyVision 1.0 User's Guide Page 9 To register this software, fill in the REGISTER.TXT registration form included in the archive. Registration is $25 CANADIAN. You will receive via 'snail mail' an official registered user certificate with your registration number. For $35 CANADIAN, you'll also receive a bonded printed copy of the latest version of this manual. EasyVision and TNG SOFT ENTERPRISES are registered trade marks. What's Next ? ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ There won't be many new commands ! EasyVision will always remain EASY to use, to leave the programmer at more important tasks. However, I welcome your suggestions to what you think is missing from this package. Remember though, that I will never include functions that are not directly related to the user interface. I will try to improve the functions and classes already there. I'd like to add an integrator for the windows, allowing background windows to be brought in the foreground, a window refresh function, better text output facilities and mouse support. So, that's about it for now ! Have fun and enjoy ! Rémy Gendron author of EasyVision EasyVision 1.0 User's Guide Page 10 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 2 Getting started ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Installing and using the EasyVision library is very simple. Library specifics ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ EasyVision was developped under TURBO C++ 1.01, then later transfered to BORLAND C++ 3.0. The code was compiled under the HUGE memory model. All prototypes were declared as FAR functions and all pointers were explicitely declared HUGE. This will provide full compatibility when linking to any memory model size. Unless you REALLY know what you are doing, you should always use HUGE pointers. FAR pointers can cause wrap around and comparison problems because they are not normalised. All EasyVision's functions use huge pointers. The video output is done through direct screen writes. This makes for incredibly fast output. Going through the BIOS is just to slow. However, under multitaskers like Deskview, who often work in textmode, screen bleeds can occur if the application is running in the background. Use the virtualising options when running under DeskView. All EasyVision's header files use conditional compilation to prevent redeclaration errors at compile time. So, if you're not sure if a header was previously included (possibly by another header file), feel free to include it again. Installation ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Unpack the archive in a temporary directory. If you haven't done so, you should really print all of the USER'S GUIDE for easier reading. It as been formatted to print at 60 lines per pages. Put all header files (.HPP) into an INCLUDE directory. Just to be sure you won't overwrite existing header files, you should make a separate include directory, then include it in the 'include' path of your compilator. Then put the EasyVision library (EVISION.LIB) into one of your LIBRARY directories. EasyVision 1.0 User's Guide Page 11 How to use this library ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ To use an EasyVision function or class, just include its header file in your source code. YOU MUST NOT write a prototype yourself based on the prototype written in this manual. The real prototypes have additional informations in them. So, for example: #include <stdio.h> // A standard header file #include "getkey.hpp" // An EasyVision header file void main () { ... // Here you can use the 'getkey' function ... return ; } You then have to link all your modules together, including the EVISION.LIB library. You do that by including EVISION.LIB in your project. EVISION.LIB must be in one of your LIBRARY directories. That's all there is to it ! If you get linker errors, that's probably because you compiled your sources in C ANSI. You must compile in C++, or else make interfaces with the 'extern C' keyword. All arguments to functions are FULLY validated. An EasyVision function will never let you get away if it is called incorrectly. If something is wrong, the program is stopped and a plain english error message tells you what went wrong, where and why ! In the function descriptions, when it says that you SHOULD NOT or CANNOT do something, it means that if you do it, you'll get an EasyVision error message. Your program will not crash ! See the chapter THINGS YOU SHOULD NOT DO for hints on things to watch out for. How to use this document ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The following conventions are used in the document: All of EasyVision's functions were declared of type far, but the far modifier was left out of the prototypes in this manual. EasyVision 1.0 User's Guide Page 12 The following symbols were used in the text: '' Regular C and C++ keywords {} EasyVision keywords <> Arguments to functions [] Optional arguments are enclosed in brakets --> Important remarks (that you MUST read) CAPS Keyboard keys Chapter 3 describes all EasyVision's functions. Chapter 4 introduces you to the basics of using a class object. Then chapters 5 to 8 describe the 4 EasyVision's classes. At the end, reference informations can be found in appendixes. I will gladly answer any questions. I WILL NOT ANSWER THROUGH NETMAIL. YOU MUST REACH ME VIA THE C++ FIDONET ECHOMAIL CONFERENCE. I think that most questions can be answered by looking at the included demo program (DEMO.CPP). EasyVision 1.0 User's Guide Page 13 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 3 Using EasyVision's Functions ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ This version of the EasyVision library has 10 functions. They provide for parameter validations, fatal errors handling, keyboard inputs, automatic F1 online help. Also, some frequently used functions have been rewritten to accept huge parameters without the need for typecasting. All these functions are fully described in the following pages. A function description uses the following format: FUNCTION NAME ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Short description of this function behavior. ■ Syntax #include "header.h" ReturnType FonctionName (<param>, <param>, ...) ; YOU MUST NEVER WRITE A PROTOTYPE FOR A FUNCTION YOURSELF. ALWAYS USE THE PROPER HEADER FILES. THEY HAVE ADDITIONAL INFORMATIONS IN THEM ! --> When parameters are in brakets ([]), they are optional. IF YOU WANT TO INCLUDE AN OPTIONAL PARAMETER, ALL PARAMETERS BEFORE THAT ONE MUST BE INCLUDED AS WELL. ■ Remarks Parameters and usage are described here when needed. ■ Return The returned value of the function is explained here. ■ Example Examples of various calls to this function. So, here are the EasyVision's functions... EasyVision 1.0 User's Guide Page 14 ASSERT ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function will ASSERTain that a <condition> is TRUE. If it is, it will return immediately with no effect, and minimum overhead. If the condition is FALSE, the program will be terminated in an orderly fashion. {assert} will clear the screen, print an error message, and terminate the program with a call to 'exit'. This closes all open files, releases any memory allocated on the heap and exit to DOS with an ERROR LEVEL of 1. ■ Syntax #include "assert.hpp" void assert (int condition [,char huge *fctname, int errorcode, char huge *errortext]) ; ■ Remarks If <condition> evaluates to FALSE, the program will be terminated and <fctname>, the current function name will be displayed. This will help find the location of the error. You can specify an error code. If 0, you must provide an error message with the parameter <errortext>. You can also use predefined error codes. In this case, you don't need to specify an error message. 1: "Not enough memory to instantiate a class on the heap." 2: "Not enough memory to create a struct on the heap." 3: "Not enough memory to allocate the requested amount of bytes." 4: "Out of memory." 5: "File not found." 6: "Path not found." 7: "File access denied." 8: "Input/Output error." 9: "Unrecoverable fatal error." ■ Return None ■ Example assert (nbrecord>0,"datasearch",0,"Database empty !") ; EasyVision 1.0 User's Guide Page 15 GETKEY ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This is a replacement for the familiar 'getch' function. ■ Syntax #include "getkey.hpp" int getkey (int filter [,char *helptext]) ; ■ Remarks One of 'getch' weakness is its inability to deal with the way extended keys are internaly represented. Those are the keys that don't have an ASCII code associated with them. For exemple, the function, arrow and editing keys all return an extended keycode. This new {getkey} function will deal with these extended keys by adding 256 to the extended key code. Appendix A lists all of the extended keycodes currently available on an extended keyboard. You MUST specify a <filter> to be used by the {getkey} function. A filter of 0 will allow any key to be read and returned by the function. You can also provide the ASCII or extended key code (remember to add 256 to the real code) of the only key allowed to be returned by the function. This provides an easy way to WAIT FOR a specific key. The function will then return with that keycode, only when that key has been pressed. --> When you call {getkey}, it will first flush the keyboard buffer of any keys already present. When waiting for a key, if the F1 key is pressed, an help window will pop up automatically ! You can optionaly give {getkey} a pointer to some context sensitive <helptext>. If no pointer is supplied, it is assumed that no help is available at this time, and the help window pops up saying so. This help window will take care of itself. You don't have to worry about screen coordinates, colors, key input or anything. The help text is an array of chars, that need not be formated in any way. The help window will read the array and display it with word wrapping at the end of the lines. It can also be of any length. If the text cannot fit in one window, a more prompt will be showned. At any time, the user can leave help with the ESC key. EasyVision 1.0 User's Guide Page 16 Any extra spaces will be removed from the text, leaving only one space between each word. Any leading spaces to a line will also be removed. If you want to begin a line with spaces, or separate some words with more than one space, you must use the underscore (_) character. You can highlight you text by surrounding characters with the tilde (~) character. --> If the F1 key is pressed, the help window is showned and closed, then the function waits for another key. F1 will never be returned by that function ! If a <filter> is provided, the F1 key will still bring the help window. Beware of NEVER setting the filter to an impossible key entry or to the F1 keycode (315), or you will be trapped by the {getkey} function ! ■ Return If a normal key was pressed, the returned value is an int representing the ASCII code of that key. (1-255) If an extended key was pressed, the returned value is an int representing the extended key code plus 256. (256-396) ■ Example getkey (0) ; // Returns the first key pressed // No help is available getkey (13,edithelp) ; // Wait for the ENTER key // With help available EasyVision 1.0 User's Guide Page 17 GETHEAP ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Getheap replaces 'farmalloc'. ■ Syntax #include "farheap.hpp" char huge *getheap (unsigned long nbytes) ; ■ Remarks Allocates <nbytes> bytes on the far heap. ■ Return In C++ you cannot assign a void pointer to a typed pointer without a typecast. As you will most often want a huge pointer to char, this is what this function returns. If you want to assign this pointer to a pointer to a different type, just use a typecast. ■ Example char huge *ptr1 ; int huge *ptr2 ; ptr1 = getheap (1024) ; ptr2 = (int huge*) getheap (100) ; FREEHEAP ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Freeheap replaces 'farfree'. ■ Syntax #include "farheap.hpp" void freeheap (void huge *heapptr) ; ■ Remarks The only difference from 'farfree' is that this function offers the convenience of accepting a huge pointer as argument. ■ Return None ■ Example char huge *ptr ; ptr = getheap (sizeof (object)) ; // Allocate memory freeheap (ptr) ; // Free memory ptr = NULL ; // Always a good idea EasyVision 1.0 User's Guide Page 18 HSTRLEN ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This is a huge version of 'strlen'. It returns the length of a string. ■ Syntax #include "hugefcts.hpp" size_t hstrlen (char huge *string) ; ■ Remarks The only difference with 'strlen' is that this function offers the convenience of accepting a huge pointer as argument. ■ Return The length of the string. The type size_t is defined in <stdio.h> as an unsigned int. ■ Example length = hstrlen (text) ; HSTRCPY ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This is a huge version of 'strcpy'. It copies a string into another. ■ Syntax #include "hugefcts.hpp" char huge *hstrcpy (char huge *dest, char huge *src) ; ■ Remarks The only difference from 'strcpy' is that this function offers the convenience of accepting huge pointers as arguments. ■ Return A huge pointer to the destination string. ■ Example char huge *string ; string = getheap (20) ; hstrcpy (string,"Hello there !") ; EasyVision 1.0 User's Guide Page 19 SAVEVIDEO ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This will save the current screen attributes in a text_info structure. It has exactly the same effects as a call to 'gettextinfo'. The difference is that it can also save the actual screen content. ■ Syntax #include "screen.hpp" void savevideo (text_info huge *ti[, char huge*huge *savedscr]) ; ■ Remarks All members of the text_info structure <ti> are filled with this function. <savedscr> is a huge pointer to a huge char pointer. If this argument is provided, the screen content will also be saved to a buffer in the heap, and the huge pointer to char will be set to point to this buffer. ■ Return None ■ Example text_info ti ; char huge *scrbfr ; savevideo (&ti,&scrbfr) ; RESTOREVIDEO ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function will restore the screen video mode and the text window size from a text_info structure. It can also restore the screen content if it was saved by a previous call to {savevideo}. ■ Syntax #include "screen.hpp" void restorevideo (text_info huge *ti[, char huge*huge *savedscr]) ; ■ Remarks The text_info structure must have been previously filled with {savevideo}. The same is true for the previous screen content. ■ Return None ■ Example restorevideo (&ti,&scrbfr) ; EasyVision 1.0 User's Guide Page 20 SAVECURSOR ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function will save all cursor attributes, INCLUDING THE CURSOR TYPE, in a {cur_info} structure. Those attributes are: colors, x pos, y pos and cursorshape. It will not save the other screen attributes, and is therefore faster than {savevideo}. ■ Syntax #include "screen.hpp" void savecursor (cur_info huge *ci) ; ■ Remarks The cur_info structure is as follow, and is defined in "screen.hpp". struct cur_info { unsigned char attribute ; // Cursor colors unsigned char curx ; // Cursor X position unsigned char cury ; // Cursor Y position unsigned int curtype ; // Cursor type } ; ■ Return None ■ Example cur_info ci ; savecursor (&ci) ; RESTORECURSOR ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function will restore all cursor attributes, INCLUDING THE CURSOR TYPE, from a cur_info structure. ■ Syntax #include "screen.hpp" void restorecursor (cur_info huge *ci) ; ■ Remarks The cursor attributes must have been previously saved with {savecursor}. ■ Return None ■ Example cur_info ci ; savecursor (&ci) ; ... restorecursor (&ci) ; EasyVision 1.0 User's Guide Page 21 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 4 Using EasyVision's Classes ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The EasyVision library has 4 classes. They provide a desktop, a statusline, a menubar and windows. Those classes are fully described in the following pages. A classe description uses the following format: First, the description of the class itself, its behavior, how it is related to the other classes and the interface. Then, each member function of the class is presented in the following format: MEMBER FUNCTION NAME ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Short description of this function behavior. ■ Syntax #include "header.h" ReturnType FonctionName (<param>, <param>, ...) ; YOU MUST NEVER WRITE A PROTOTYPE FOR A FUNCTION YOURSELF. ALWAYS USE THE PROPER HEADER FILES. THEY HAVE ADDITIONAL INFORMATIONS IN THEM ! --> When parameters are in brakets ([]), they are optional. IF YOU WANT TO INCLUDE AN OPTIONAL PARAMETER, ALL PARAMETERS BEFORE THAT ONE MUST BE INCLUDED AS WELL. ■ Remarks Parameters and usage are described here when needed. ■ Return The returned value of the function is explained here. ■ Example Examples of various calls to this function. Using classes is quite easy ! First you declare a pointer to this class. Then you instantiate (create) an object of this class type with the operator 'new'. Now you can call the classe's member functions with the '->' operator. When you're finished, you free the memory taken by this class instance with 'delete'. Many examples are available in the source code of the EasyVision demo program (DEMO.CPP). EasyVision 1.0 User's Guide Page 22 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 5 EasyVision's TDESKTOP class ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The {tdesktop} class is the first one to be instantiated in a program that uses the EasyVision user interface. This class will save the current screen, initialise the video screen to the video mode of your choice, and display the desktop. The desktop is the background on which the menubar, the statusline and your windows will be displayed. You will also call this class at the end of your program to restore the previous video mode, restore the previous screen and reset default colors and cursor position. The {tdesktop} class as built in default values. Only one call is required to do the work. The desktop will autosize itself to the screen. However, if you would like to change those default behaviors, other functions are provided to do so. The {tdesktop} class can be used alone by itself. That is, it can be the only class you will use in your application. On the following pages, you will find each of tdesktop's member functions. An example of instantiating a {tdesktop} object is given in the source code of the EasyVision's demo program (DEMO.CPP). EasyVision 1.0 User's Guide Page 23 TDESKTOP::SETTEXTMODE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the textmode in which {open} will draw the desktop. This has no effect on the current textmode. It will only take effect when {open} will be called. The {refresh} function uses the current textmode. This call is optional. If it is not made before a call to {open}, textmode C80 (3) is assumed. ■ Syntax #include "tdesktop.hpp" void settextmode (int mode) ; ■ Remarks Symbolic constant | Value | Text mode ------------------+-------+------------------------- LASTMODE | -1 | Previous text mode BW40 | 0 | Black and white, 40 cols C40 | 1 | Color, 40 columns BW80 | 2 | Black and white, 80 cols C80 | 3 | Color, 80 columns MONO | 7 | Monochrome, 80 columns C4350 | 64 | EGA 43-line, VGA 50-line To use the symbolic constants, <conio.h> must be included. ■ Return None ■ Example desktop->settextmode (C80) ; TDESKTOP::SETDESKCOLORS ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the colors in which {open} or {refresh} will draw the desktop. ■ Syntax #include "tdesktop.hpp" void setdeskcolors (int back, int fore) ; ■ Remarks This has no effect on the current colors. It will only be used when {open} or {refresh} will be called. This call is optional. If {setdeskcolors} is not called before a call to {open}, BLUE on LIGHTGRAY is assumed. See appendix B for a list of available colors, color codes and symbolic constants. ■ Return None ■ Example desktop->setdeskcolors (RED,LIGHTGRAY) ; EasyVision 1.0 User's Guide Page 24 TDESKTOP::SETTEXTURE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the character with which {open} or {refresh} will draw the desktop. ■ Syntax #include "tdesktop.hpp" void settexture (char asciicode) ; ■ Remarks You must provide the character used to draw the desktop, in the form of its ASCII code. Only ASCII code greater or equal to 32 are accepted. This has no effect on the current screen. It will only be used when {open} or {refresh} will be called. This call is optional. If {settexture} is not called before a call to {open}, '░' is assumed. ■ Return None ■ Example desktop->settexture (' ') ; // Plain desktop TDESKTOP::SETTITLE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the title, and title colors displayed at the very top line of the desktop. ■ Syntax #include "tdesktop.hpp" void settitle (char huge *text[, int back, int fore]) ; ■ Remarks The colors for the title are optional. If they are not provided, the desktop's colors will be used. This is used only if you do not intend to have a menubar, or if you will have something displayed before the menubar is created. This has no effect on the current desktop. It will only be used when {open} or {refresh} will be called. This call is optional. If {settitle} is not called before a call to {open}, no title will be displayed. To reset a previously defined title, use "" as argument. You can give a <text> pointer argument that points to a text of any length, but only the part of the title that will fit on the titlebar will be displayed. So don't worry about the length of your title... ■ Return None ■ Example desktop->settitle ("EasyVision 1.0",RED,BLACK) ; EasyVision 1.0 User's Guide Page 25 TDESKTOP::OPEN ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Opens the desktop. ■ Syntax #include "tdesktop.hpp" void open () ; ■ Remarks This will save the screen before the program was started, initialise the video screen and then display the desktop according to the default values, or those set by the previous functions. This call is NOT optional. You cannot 'reopen' an already opened desktop. You must use the {refresh} function for that action, or first close it. If the desktop as been closed, it can then be re- opened. This could be done for instance if you were to shell to DOS or to another program. ■ Return None ■ Example desktop->open () ; TDESKTOP::CLOSE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Closes the Desktop. ■ Syntax #include "tdesktop.hpp" void close () ; ■ Remarks This will restore the video screen as it were before the desktop was opened. This call is NOT optional. You must first {close} the desktop with this function if you want to re-open it. {close} does not reset any of the desktop settings. You can easily re-open it after a shell to DOS for example. ■ Return None ■ Example desktop->close () ; EasyVision 1.0 User's Guide Page 26 TDESKTOP::INSERT ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Insert a {tstatusline} or {tmenubar} object into the desktop. ■ Syntax #include "tdesktop.hpp" void insert (tstatusline huge *sl) ; void insert (tmenubar huge *mb) ; ■ Remarks The desktop has a {refresh} function that will redraw the screen. Initialy, it will only redraw the desktop. If you want it to be able to redraw the statusline and menubar, you must {insert} them into the desktop. This function is overloaded. You use the same function to insert the statusline or the menubar. --> You cannot insert more than one object of the same type in the desktop, or the previous one will be lost. ■ Return None ■ Example desktop->insert (statusline) ; DESKTOP::REFRESH ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary The desktop has a {refresh} function that will redraw the screen. Using this function can be DANGEROUS... ■ Syntax #include "tdesktop.hpp" void refresh () ; ■ Remarks If you want it to be able to redraw the statusline and menubar, you must first {insert} them into the desktop. --> The refresh function will use the current values for colors, texture, etc... not the values when it was opened. This means that you can change the desktop colors for instance, and then {refresh} it. --> IN EASYVISION 1.0, WINDOWS CANNOT BE REFRESHED. YOU MUST MAKE ABSOLUTELY CERTAIN THAT THIS FUNCTION CANNOT BE CALLED WHEN WINDOWS ARE OPENED, OR YOU WILL BE IN BIG TROUBLE. ■ Return None ■ Example desktop->refresh () ; EasyVision 1.0 User's Guide Page 27 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 6 EasyVision's TSTATUSLINE class ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The {tstatusline} class provides a standard statusline on the last line of the screen. It is divided into 2 areas, each one completely independent. The left area is 10 spaces wide, including the dividing character '|'. You have 8 spaces to display a message in this area. The suggested message for this area is '~F1~ Help'. The right area occupies the remainder of the line. The {tstatusline} class as built in default values. The statusline will autosize itself to the screen. However, if you would like to change those default beheviors, other functions will allow you to do so. The {tstatusline} class can be used alone by itself. That is, it can be the only class you will use in your application. On the following pages, you will find each of the tstatusline's member functions. Examples of instantiating a {tstatusline} object are given in the source code of the EasyVision's demo program (DEMO.CPP). EasyVision 1.0 User's Guide Page 28 TSTATUSLINE::SETLEFTCOLORS ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the background, foreground and highlight colors used by the {displayleft} function, when writing to the left statusline. ■ Syntax #include "tstatusline.hpp" void setleftcolors (int back[, int fore, int high]) ; ■ Remarks <fore> and <high> are optional. If they are not provided, <fore> defaults to BLACK, and <high> to RED. You can use color macros if <conio.h> is included. Appendix B gives a descrition of available color codes and macros. ■ Return None ■ Example statusline->setleftcolors (LIGHTGRAY,BLACK,RED) ; TSTATUSLINE::SETRIGHTCOLORS ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the background, foreground and highlight colors used by the {displayright} function, when writing to the right statusline. ■ Syntax #include "tstatusline.hpp" void setrightcolors (int back[, int fore, int high]) ; ■ Remarks <fore> and <high> are optional. If they are not provided, <fore> defaults to BLACK, and <high> to RED. You can use color macros if <conio.h> is included. Appendix B gives a descrition of available color codes and macros. ■ Return None ■ Example statusline->setrightcolors (LIGHTGRAY,BLACK,RED) ; EasyVision 1.0 User's Guide Page 29 TSTATUSLINE::DISPLAYLEFT ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Displays a message on the statusline, in the left area. ■ Syntax #include "tstatusline.hpp" void displayleft ([char huge *text]) ; ■ Remarks The <text> argument can point to a msg of any length, including the '~' characters. If the message is too long to fit in the area, only the first 8 characters will be displayed. There is no need to clear the statusline before using this function. You can toggle between normal foreground statusline color and the highlight color with the special character '~' (tilde). To clear the statusline, call this function with no parameter. ■ Return None ■ Example statusline->displayleft ("~F1~ Help") ; // Display text statusline->displayleft () ; // Clear left statusline TSTATUSLINE::DISPLAYRIGHT ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Displays a message on the statusline, in the right area. ■ Syntax #include "tstatusline.hpp" void displayright ([char huge *text]) ; ■ Remarks The <text> argument can point to a msg of any length, including the '~' characters. If the message is too long to fit in the area, only the first 'n-2' characters will be displayed, assuming the right area is n characters wide. There is no need to clear the statusline before using this function. You can toggle between normal foreground statusline color and the highlight color with the special character '~' (tilde). To clear the statusline, call this function with no parameter. ■ Return None ■ Example statusline->displayright ("This is ~EasyVision~ !") ; statusline->displayright () ; // Clear right area EasyVision 1.0 User's Guide Page 30 TSTATUSLINE::REFRESH ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary The statusline object has a {refresh} function that will redraw it on the screen. ■ Syntax #include "tstatusline.hpp" void refresh () ; ■ Remarks It will redraw the statusline and redisplay the last message. --> The refresh function will use the current values for colors. This means that you can change the statusline colors and then, {refresh} it with the new colors. ■ Return None ■ Example statusline->refresh () ; EasyVision 1.0 User's Guide Page 31 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 7 EasyVision's TMENUBAR class ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The {tmenubar} class provides a menubar on the first line of the screen, with pull down menus and scrolling selection cursor. It also activates an interrupt driven clock displayed at the end of the menubar. A menubar acts as a filter. You make the user inputs go 'trough' the menubar. If the input is the F10 key, or an ALT-key corresponding to a menu hotkey, the menubar is activated. If not, the input returns unchanged. Items created in the menus are assigned return values. When the user selects an item, his input is changed to this return value and returned from the menubar. The {tmenubar} class as built in default values. The menubar will autosize itself to the screen. However, if you would like to change those default beheviors, functions will allow you to do so. The {tmenubar} class can be used alone by itself. That is, it can be the only class you will use in your application. YOU SHOULD NEVER INSTANTIATE MORE THAN ONE MENUBAR. RESULTS COULD BE DANGEROUS. On the following pages, you will find each of {tmenubar}'s member functions. Examples of instantiating and using a {tmenubar} object are given in the source code of the EasyVision's demo program (DEMO.CPP). EasyVision 1.0 User's Guide Page 32 TMENUBAR::SETCOLORS ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the background, foreground, highlight, cursor and clock colors used by the {tmenubar} object. ■ Syntax #include "tmenubar.hpp" void setcolors ([int back, int fore, int high, int cursor, int clockback, int clockfore]) ; ■ Remarks All arguments are optional. If they are not provided, they will default to the following values: back = LIGHTGRAY fore = BLACK high = RED cursor = GREEN clockback = RED clockfore = WHITE You can use color macros if <conio.h> is included. Appendix B gives a descrition of available color codes and macros. If you don't make a call to this function, the previously mentioned default values are assumed. --> When a menu has been created, it is thereafter illegal to change the allready selected colors. ■ Return None ■ Example menubar->setcolors (BLUE,WHITE,RED,MAGENTA) ; EasyVision 1.0 User's Guide Page 33 TMENUBAR::SETHELP ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the pointer to some help text that will be displayed when F1 is pressed while in the menubar. ■ Syntax #include "tmenubar.hpp" void sethelp (char huge *helptext) ; ■ Remarks The help text format is explained in the {getkey} function description. ■ Return None ■ Example menubar->sethelp (menuhelp) ; TMENUBAR::SETSLPTR ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the pointer to the statusline. ■ Syntax #include "tmenubar.hpp" void setslptr (tstatusline huge *slptr) ; ■ Remarks When you create menus and menu items, you can optionaly give them a short help text that will be displayed on the statusline when the menu cursor is on them. You therefore need to tell the menubar where is the statusline object. This is optional. If this pointer is not set, the statusline help texts will not be displayed. ■ Return None ■ Example menubar->setslptr (statusline) ; EasyVision 1.0 User's Guide Page 34 TMENUBAR::ADDMENU ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Adds a menu on the menubar. ■ Syntax #include "tmenubar.hpp" void addmenu (char huge *name, int hotkey[, char huge *sltext]) ; ■ Remarks <name> : It can be of any length, but must fit on the menubar. The first 2 characters of the menubar are left blank, and the 10 lasts are reserved for the menubar clock. 2 spaces will be inserted between each menu. <hotkey>: It must be a letter (A-Z), case insensitive. If the letter is present in the menu name, it will be highlighted. <sltext>: This is a short help text that will be displayed on the statusline when this menu is selected. It can be of any length. {setslptr} must have been previously called. ■ Return None ■ Example menubar->addmenu ("Files",'F',"Create, open files") ; EasyVision 1.0 User's Guide Page 35 TMENUBAR::ADDITEM ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Adds an item in the last created menu. ■ Syntax #include "tmenubar.hpp" void additem ([char huge *text, int hotkey, int returnval, char huge *sltext]) ; ■ Remarks <text> : This is the text displayed for this menu entry. It can be of any length. The menu will autosize itself to accomadate the widest item. <hotkey>: It must be a letter (A-Z), case insensitive. If the letter is present in the item text, it will be highlighted. <returnval>: If this item is selected, the user input will be change to this value. <sltext>: This is a short help text that will be displayed on the statusline when this item is selected. It can be of any length. {setslptr} must have been previously called. --> If {additem} is called with no arguments, it will insert a separator in the menu. ■ Return None ■ Example menubar->additem ("Open F3",'O',317,"Open file") ; EasyVision 1.0 User's Guide Page 36 TMENUBAR::TROUGH ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Makes an input go trough the menubar. ■ Syntax #include "tmenubar.hpp" int trough (int key) ; ■ Remarks If <key> is F10, the menubar is activated, but no menus are opened. If <key> is a menu hotkey, this menu is opened. ■ Return If <key> is not F10 or a menu hotkey, {trough} returns <key> unchanged. If the menubar is activated, then if the user enters ESC, {trough} returns with 0. Otherwise it returns with the return value of the menu item selected. ■ Example int inchar ; inchar = menubar->trough (getkey (0)) ; TMENUBAR::ITEMSETAVAIL ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets availability of a menu item to TRUE or FALSE. ■ Syntax #include "tmenubar.hpp" void itemsetavail (int menuhotkey, int itemhotkey, int state) ; ■ Remarks You must provide the <menuhotkey> of the menu in which the item exist, and the <itemhotkey> of the item itself. Setting a menu item to TRUE will make it available, to FALSE not available. --> When a menu item is created, it is available by default. ■ Return None ■ Example menubar->itemsetavail ('F','O',FALSE) ; EasyVision 1.0 User's Guide Page 37 TMENUBAR::REFRESH ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary The menubar object has a {refresh} function that will redraw it on the screen. ■ Syntax #include "tmenubar.hpp" void refresh () ; ■ Remarks None ■ Return None ■ Example menubar->refresh () ; EasyVision 1.0 User's Guide Page 38 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 8 EasyVision's TWINDOW class ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The {twindow} class provides powerful window functions to your programs. A window is where all your program's screen inputs/outputs will take place. The {twindow} class comes with many member functions. They allow for manipulating the window position, size and attributes. Text can be easily written to the window. Input fields will give you formatted and secured user inputs. Push buttons will provide options selection. All this and many more features. The {twindow} class as built in default values. However, if you would like to change those default beheviors, functions will allow you to do so. The {twindow} class can be used alone by itself. That is, it can be the only class you will use in your application. --> You can open simultanously as many windows as you like. When you open a window, what was under it is saved to be restored when you'll close it. --> EasyVision doesn't keep track of the way windows overlap. It doesn't know if a window is over or under another one. Therefore, you should NEVER close a window if another window covers part of it. Always close the ones that are in the foreground first. --> You must NEVER work with a window that is under another one. If you do so, the integrity of the desktop will be compromised. On the following pages, you will find each of {twindow}'s member functions. Examples of instantiating and using a {twindow} object are given in the source code of the EasyVision's demo program (DEMO.CPP). EasyVision 1.0 User's Guide Page 39 TWINDOW::WINGETSCREENHEIGHT ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Returns the video screen height in lines. ■ Syntax #include "twindow.hpp" int wingetscreenheight () ; ■ Remarks This could be needed if you wanted to center a window. ■ Return An 'int', the height of the screen. ■ Example lines = window->wingetscreenheight () ; TWINDOW::WINGETSCREENWIDTH ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Returns the video screen width in columns. ■ Syntax #include "twindow.hpp" int wingetscreenwidth () ; ■ Remarks This could be needed if you wanted to center a window. ■ Return An 'int', the width of the screen. ■ Example Cols = window->wingetscreenwidth () ; EasyVision 1.0 User's Guide Page 40 TWINDOW::WINSETPOS ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the position of the window on the desktop. ■ Syntax #include "twindow.hpp" void winsetpos (int row, int col) ; ■ Remarks <row> and <col> are the topleft corner of the window TO BE OPENED. The first and last lines of the desktop are reserved for the menubar and statusline and you can't have part of the window off the screen. Therefore, this function will validate all coordinates and change them to get a valide window position. --> If you set the size of the window before setting its position, this size will be taken into account to calculate the valide range of the <row> and <col> arguments. --> You CANNOT use this function once the window has been opened. Use the {winmove} function instead. ■ Return None ■ Example window->winsetpos (10,12) ; // Topleft corner at 10,12 EasyVision 1.0 User's Guide Page 41 TWINDOW::WINGETROW ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Returns the window row position of its topleft corner. ■ Syntax #include "twindow.hpp" int wingetrow () ; ■ Remarks The top left corner of the screen is (1,1). ■ Return Row position of window. ■ Example row = window->wingetrow () ; TWINDOW::WINGETCOL ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Returns the window column position, topleft corner. ■ Syntax #include "twindow.hpp" int wingetcol () ; ■ Remarks The top left corner of the screen is (1,1). ■ Return Column position of window. ■ Example col = window->wingetcol () ; EasyVision 1.0 User's Guide Page 42 TWINDOW::WINSETSIZE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the size of the window. ■ Syntax #include "twindow.hpp" void winsetsize (int height, int width) ; ■ Remarks <height> and <width> represent the size of the window, frames included. The first and last lines of the desktop are reserved for the menubar and statusline. Also, you can't have part of the window off the screen. Therefore, this function will validate the asked size and change it to get a valide window size. --> You CANNOT change the size of a window once it has been opened. ■ Return None ■ Example window->winsetsize (10,60) ; // 10 rows by 60 cols TWINDOW::WINGETHEIGHT ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Returns the window's height in lines. ■ Syntax #include "twindow.hpp" int wingetheight () ; ■ Remarks The top and bottom frames are included in the height. ■ Return An 'int', the height of the window. ■ Example heigth = window->wingetheight () ; TWINDOW::WINGETWIDTH ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Returns the window's width in columns. ■ Syntax #include "twindow.hpp" int wingetwidth () ; ■ Remarks The left and right frames are included in the width. ■ Return An 'int', the width of the window. ■ Example width = window->wingetwidth () ; EasyVision 1.0 User's Guide Page 43 TWINDOW::WINSETCOLORS ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the background and foreground colors of a window. ■ Syntax #include "twindow.hpp" void winsetcolors ([int back, int fore]) ; ■ Remarks These are the colors used to draw the window. Those colors will be used by other functions when the color arguments are optional. <back> and <fore> are optional, and will default to LIGHTGRAY and WHITE respectively. --> You CANNOT change the default colors of a window once it has been opened. ■ Return None ■ Example window->winsetcolors (BLUE,WHITE) ; TWINDOW::WINSETTITLE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the title displayed on the top frame of a window. ■ Syntax #include "twindow.hpp" void winsettitle (char huge *title) ; ■ Remarks <title> can point to a title of any length, and only the portion that will fit on the top frame will be displayed. If you don't give a title before opening a window, no title will be displayed. --> You CANNOT set a title after a window has been opened. ■ Return None ■ Example window->winsettitle ("User's file") ; EasyVision 1.0 User's Guide Page 44 TWINDOW::WINSETHELP ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets a pointer to some context sensitive help text that will be displayed if the F1 help key is pressed while in this window. ■ Syntax #include "twindow.hpp" void winsethelp (char huge *ptrtohelp) ; ■ Remarks The format of the help text is described in the {getkey} function. ■ Return None ■ Example window->winsethelp (inputhelp) ; TWINDOW::WINSETSLPTR ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets a pointer to an instantiated {tstatusline} object. ■ Syntax #include "twindow.hpp" void winsetslptr (tstatusline huge *slptr) ; ■ Remarks Input fields and buttons in a window can be given a short help text that will be displayed on the statusline when they are selected. To enable this function, you must give the window a ptr to your statusline. ■ Return None ■ Example window->winsetslptr (statusline) ; EasyVision 1.0 User's Guide Page 45 TWINDOW::WINOPEN ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Opens a window. ■ Syntax #include "twindow.hpp" void winopen () ; ■ Remarks The window is opened with default attributes, or the ones set by the previous functions. You CANNOT open an already opened window. Default attributes for a window are: Position is (row=2, col=1). Size is (height=3, width=6). Colors are WHITE on LIGHTGRAY. The cursor is on line 1. ■ Return None ■ Example window->winopen () ; TWINDOW::WINCLOSE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Closes a window. ■ Syntax #include "twindow.hpp" void winclose () ; ■ Remarks You CANNOT close an already closed window. When you close a window, all its attributes are reset to their default values as if you had just declared this object. Your previous settings like size and colors aren't in effect anymore. All memory taken by the window is released. What was under this window when it was opened is restored. --> You should NEVER close a window that has part of itself hidden under another window. Always close the ones in the foreground first. This is your responsability ! EasyVision doesn't know your window layer position and won't tell you if something goes wrong. ■ Return None ■ Example window->winclose () ; EasyVision 1.0 User's Guide Page 46 TWINDOW::WINCLEAR ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Clears part or all the window content. ■ Syntax #include "twindow.hpp" void winclear ([int left, int top, int right, int bottom]) ; ■ Remarks The window must be opened to call this function. All arguments are validated and if incorrect, changed to fall within valide window coordinates. All arguments are optional, and will default to: left = 1 , top = 1, right = rightmost column, bottom = bottom line. So, calling this function with no arguments will clear the entire window. --> Beware that this function will also clear static text, buttons and input fields, BUT NOT REMOVE THEM. This will make them invisible, until you use them again. It is your responsability to make sure you don't erase them ! ■ Return None ■ Example window->winclear (1,1,999,3) ; // Erases first 3 lines EasyVision 1.0 User's Guide Page 47 TWINDOW::WINWRITE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Writes text to the window. Many options are available. ■ Syntax #include "twindow.hpp" void winwrite (char huge *text[, int row, int col, int format, int fore, int back]) ; ■ Remarks The window must be opened. The <text> argument can point to a text string of any length, but only the first 132 characters will be considered. --> This function will only print on 1 line of the window. If the string is longer than an entire line, only what will fit will be printed. NO LINE WRAPPING WILL OCCUR with this function ! All arguments are optional, except for <text>. <text> : Pointer to the text to be printed. <row> : The {winwrite} function keeps track of the last line printed to, with an internal cursor. After each {winwrite}, the cursor is positioned on the next line. When you use <row>, it tells where the text is to be printed. Row 1 is the first line under the top frame. This argument is optional. If it is not given, or if you use the macro 'WSAME', {winwrite} will use it's internal cursor position. Text will be printed on the cursor line, and the cursor will move to the next line. --> If you DON'T give the <row> argument and write to the last window line, all the window will be scrolled up 1 line. YOU MUST MAKE SURE YOU DON'T HAVE ANY STATIC TEXT, BUTTONS OR INPUT FIELDS. THEY WILL BE SCROLLED UP ALSO AND THE WINDOW INTEGRITY WILL HAVE BEEN COMPROMISED ! --> If you give the <row> argument, you can then write to the last line and no scrolling will occur. The window cursor will stay on the last line. EasyVision 1.0 User's Guide Page 48 <col> : Column where text will start. This argument is optional. If it is not given, or if you use the macro 'WSAME', it will default to 1. <format>: Determines how the text string is justify. 0: No justification. <col> is used. 1: Left justified. <col> has no effect. 2: Centered. <col> has no effect. 3: Right justified. <col> has no effect. This argument is optional. If it is not given, it will default to 0. <fore> : Foreground color used. This argument is optional. It it is not given, or if you use the macro 'WSAME', it will default to the window foreground color. <back> : Background color used. This argument is optional. If it is not given, or if you use the macro 'WSAME', it will default to the window background color. ■ Return None ■ Example // Writes to current line, left justified, current // window colors, and move cursor to next line window->winwrite ("Hello") ; // Writes to current line, centered, current window // colors, and move cursor to next line. Even if // <col> is 1, it has no effect. window->winwrite ("Hello",WSAME,1,2) ; // Writes to specific line, specific column, specific // colors window->winwrite ("Hello",5,10,0,YELLOW,RED) ; EasyVision 1.0 User's Guide Page 49 TWINDOW::WINSWRITE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Writes STATIC text to the window. Many options are available. ■ Syntax #include "twindow.hpp" void winswrite (char huge *text[, int row, int col, int format, int fore, int back]) ; ■ Remarks All comments for {winwrite} are still true for {winswrite}. Currently, the {twindow} class doesn't have a {refresh} function like the {tdesktop}, {tstatusline} and {tmenubar} classes. The {winswrite} function has been implemented to make possible a future {refresh} function. The {winswrite} function acts exactly as the {winwrite} function. However, all the calls to {winswrite} are saved in a queue. Later, when the {refresh} function is implemented, all calls to {winswrite} will be remade to redisplay those static texts. --> All calls to this function allocate memory, and are much slower than a call to the regular {winwrite}. {winswrite} SHOULD ONLY BE USED for text that will not be erased until the window is closed. For instance, an identifier for an input field, or some other identifications. --> You SOULD NEVER USE this function if you intend to scroll the window or erase it. Use it only if you want your text to be available to the {refresh} function. ■ Return None ■ Example See the {winwrite} examples EasyVision 1.0 User's Guide Page 50 TWINDOW::WINTEXT ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Displays a text array in current window with word wrapping and 'PgDown/Esc' prompts. ■ Syntax #include "twindow.hpp" void wintext (char huge *textptr [,int fore, int high, int helpflag]) ; ■ Remarks The window must be opened to call this function. <textptr>:This points to the text to be displayed. This text can be of any length. The format of this text is explained in the {getkey} function. A 'PgDown' prompt will be created to allow the user to see the remaining text if it couldn't all fit in the window. An 'Esc' prompt will be created to allow the user to stop viewing text at his convenience. --> When you use this function, make sure the window is totally empty. Everything that was in the window is erased when you call this function. <fore> : Foreground color used. This argument is optional. If it is not given, or if you use the macro 'WSAME', the default foreground color of the window will be used. <high> : Highlight color used. This argument is optional. If it is not given, the color YELLOW will be used for highlights. <helpflag>: Determines if the F1 help key will be available when the text is displayed. 0 means NO, 1 means YES. This argument is optional and default to 1. You should never have to set this to 0. It's internaly used to prevent the F1 help routine to call itself from help. ■ Return None ■ Example window->wintext (instructions) ; EasyVision 1.0 User's Guide Page 51 TWINDOW::WINTEXTFILE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Displays a text file from disk in current window with word wrapping and 'PgDown/Esc' prompts. ■ Syntax #include "twindow.hpp" void wintextfile (char huge *path [,int fore, int high]) ; ■ Remarks This function acts exactly the same as {wintext}. The only difference is that it gets it's input text from a disk file. <path> : Complete path to disk file. If the file cannot be found, 'File not found' is displayed instead. <fore> : Foreground color used. This argument is optional. If it is not given, or if you use the macro 'WSAME', the default foreground color of the window will be used. <high> : Highlight color used. This argument is optional. If it is not given, the color YELLOW will be used for highlights. --> The <helpflag> argument is not used. Help is always available. ■ Return None ■ Example window->wintextfile ("C:\\autoexec.bat") ; EasyVision 1.0 User's Guide Page 52 TWINDOW::WINMOVE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Moves the windows to a new location. ■ Syntax #include "twindow.hpp" void winmove (int row, int col) ; ■ Remarks The window must be opened. <row> and <col> are the topleft corner of the window. The first and last lines of the desktop are reserved for the menubar and statusline and you can't have part of the window off the screen. Therefore, this function will validate all coordinates and change them to get a valide window position. ■ Return None ■ Example window->winmove (10,12) ; TWINDOW::WINSCROLL ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Moves window in 1 of 4 direction. ■ Syntax #include "twindow.hpp" void winscroll (char direction) ; ■ Remarks The entire window will be moved, if possible, 1 character in the requested direction. The name can be a little confusing. It is not the window content that is scrolled. It's the entire window. The argument is a character, case insensitive: U: Up, D: Down, L: Left, R: Right. ■ Return None ■ Example window->winscroll ('U') ; // Move window up 1 line EasyVision 1.0 User's Guide Page 53 TWINDOW::WININPUT ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Allow inputs to be made in multiple input fields, and push buttons selection. ■ Syntax #include "twindow.hpp" int wininput () ; ■ Remarks You must have created at least 1 input field prior to calling this function. The user will be able to move between input fields and buttons with TAB and SHIFT-TAB. ■ Return If no push buttons were created, {wininput} will return with 13 or 27. 13 means the user confirmed the inputs by pressing ENTER. 27 means the user aborted the input by pressing ESC. If buttons were created, {wininput} will return with the identification value of the button pushed. ■ Example userinput = window->wininput () ; EasyVision 1.0 User's Guide Page 54 TWINDOW::FIELDSETLENGTHS ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the length of the next input field to be created and the length of its answer buffer. ■ Syntax #include "twindow.hpp" void fieldsetlengths (int answer, int field) ; ■ Remarks <answer>: The maximum length of the input buffer. The user is allow to enter a string no longer than this limit. The upper limit is 32K. That should be enough ! <field> : The length of the input field in the window in characters. The input field cannot be wider than the window. The input field cannot be wider than the answer buffer length. ■ Return None ■ Example window->fieldsetlengths (40,20) ; TWINDOW::FIELDSETCOLORS ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the colors used in the next input field to be created. ■ Syntax #include "twindow.hpp" void fieldsetcolors ([int back, int foreon, int foreoff]) ; ■ Remarks <back> : Background color used. This argument is optional. If it is not given, or if the macro 'WSAME' is used, it will default to the window default background color. <foreon>: Foreground color used when the field is active. This argument is optional. If it is not given, it will default to WHITE. <foreoff>:Foreground color used when the field is inactive. This argument is optional. If it is not given, it will default to DARKGRAY. ■ Return None ■ Example window->fieldsetcolors (GREEN,WHITE,WHITE) ; EasyVision 1.0 User's Guide Page 55 TWINDOW::FIELDSETFTR ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the filter for the next input field to be created. ■ Syntax #include "twindow.hpp" void fieldsetftr (int ftrtype [,char huge *extra]) ; ■ Remarks An input field will allow only certain characters as input. <ftrtype> will determine what characters are accepted. 0: All characters are allowed, except control chars. 1: A-Z and a-z only. *** Space (32) not allowed *** 2: 0-9 only. 3: A-Z, a-z and 0-9 only. 4: No characters allowed. <extra> : Include, between quotes, other characters that you want accepted by the filter. Often used to include the space char (ASCII 32). ■ Return None ■ Example window->fieldsetftr (3,"\:_") ; // Enough for a path TWINDOW::FIELDSETATTRIB ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets attributes for the next input field to be created. ■ Syntax #include "twindow.hpp" void fieldsetattrib ([int caps, int restore, int empty]) ; ■ Remarks <caps> : If set to 1, all inputs will be converted to CAPS. This argument is optional and will default to 0. <restore>:If set to 1, what was under a field will be restored when the field is inactive. This argument is optional and will default to 0. <empty> : If set to 0, the user won't be allowed to input an empty string. This argument is optional and will default to 1. ■ Return None ■ Example window->fieldsetattrib (1) ; // Switch to CAPS EasyVision 1.0 User's Guide Page 56 TWINDOW::FIELDCREATE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Create a new input field in the window. ■ Syntax #include "twindow.hpp" void fieldcreate (int row, int col [,char huge *defaultasw, char huge *sltext]) ; ■ Remarks The window must be opened prior to calling this function. Fields have default built in behaviors when a window is first created. If you don't call any function to set their attributes, buttons will default to the following: The field and the answer buffer will have a length of 1 character. The field will be WHITE on BLUE. The default filter will be 1, with no extra characters. CAPS LOCK will not be activated, what is under the field won't be restored when the field is inactive, and the user will be permitted to enter an empty string. <row> : Row of input field. <col> : Column of input field. <row> and <col> are validated to make sure the input field fits into the window. If the position is incorrect, it will be automatically changed. <defaultasw>: This is the default answer that will be put in the input field. This argument is optional. If it is not given, the field will be initialy empty. <sltext>: This is a short help text that will be displayed on the status line when the field is active. This arguement is optional. If it is not given, no help text will be displayed. {winsetslptr} must have been called. ■ Return None ■ Example window->fieldcreate (2,2,"Canada","Enter country") ; EasyVision 1.0 User's Guide Page 57 TWINDOW::FIELDINPUT ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Get user input from one input field. ■ Syntax #include "twindow.hpp" int fieldinput ([int fieldnb]) ; ■ Remarks You must have created at least 1 input field to use this function. Fields are given numbers when they are created. The first field created is number 1. <fieldnb>:This is the field from which you will make the input. This field must exist. This argument is optional. If it is not given, it will default to 1. If you want to take inputs from many fields, you should consider using the {wininput} function instead. ■ Return {fieldinput} with return with an ASCII code representing how the user terminated the input. This can be CR, ESC, TAB or SHIFT-TAB. ■ Example window->fieldinput (f) ; EasyVision 1.0 User's Guide Page 58 TWINDOW::FIELDSETASW ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets a field current content. ■ Syntax #include "twindow.hpp" void fieldsetasw (char huge *answer [,int fieldnb]) ; ■ Remarks Even if the content is immediately changed, the field on the screen will be updated only when it is activated. <answer>: String to copy to the field. It can be of any length, but only what will fit in the answer buffer will be copied. <fieldnb>:Number of the field to copy to. This argument is optional and will default to 1. ■ Return None ■ Example window->fieldsetasw ("C:\\UTILS\\",5) ; TWINDOW::FIELDGETASW ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Reads the content of the answer buffer of an input field. ■ Syntax #include "twindow.hpp" void fieldgetasw (char huge *dest [,int fieldnb]) ; ■ Remarks The answer buffer of field <fieldnb> is copied to <dest>. <fieldnb> is optional and will default to 1. --> There is no way for the function to know if your destination is big enough to hold the content of the answer buffer. YOU MUST MAKE ABSOLUTELY SURE THAT YOUR DESTINATION IS AS BIG AS THE ANSWER BUFFER. ■ Return None ■ Example window->fieldgetasw (response,nb) ; EasyVision 1.0 User's Guide Page 59 TWINDOW::BUTTONSETCOLORS ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the colors used for all the window's buttons. ■ Syntax #include "twindow.hpp" void buttonsetcolors ([int back, int foreon, int foreoff, int high]) ; ■ Remarks All buttons use the same color configuration. You can't use this function once a button has been created. <back> : Background color of all buttons. This argument is optional and will default to GREEN. <foreon>: Foreground color of active buttons. This argument is optional and will default to WHITE. <foreoff>:Foreground color of inactive buttons. This argument is optional and will default to BLACK. <high> : Highlight color of all buttons. This argument is optional and will default to YELLOW. ■ Return None ■ Example window->buttonsetcolors (BLUE,WHITE,BLACK,RED) ; EasyVision 1.0 User's Guide Page 60 TWINDOW::BUTTONCREATE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Creates a new button. ■ Syntax #include "twindow.hpp" void buttoncreate (int row, int col, char huge *name, int buttonkey [,char huge *sltext]) ; ■ Remarks The window must be opened to use this function. The window must be big enough to hold the button. It must be at least 4 lines high, and 11 columns wide. You can create as many buttons as you want. There is no upper limit. Button have default built in values when a window is first created. You don't need to call the {buttonsetcolors} function. If you don't, buttons will default to a GREEN background, WHITE text when active, BLACK text when inactive, and YELLOW highlight. The availability status of a newly created button always defaults to 1 (available). The first button created will be considered the default button. This button will be activated when you request a {buttoninput}. <row> : Row position of the new button. <col> : Column position of the new button. If <row> and <col> are not valide, they will be changed to a correct position. --> You must make sure buttons don't overlap. A button needs an empty line under and to the right of itself. <name> : The name to put on the button. It can be of any length, but only the first 8 characters will be considered. Names aren't automatically centered on the buttons. Center the name manually by inserting spaces in the name. <buttonkey>: This is the ASCII code that will identify a particular button. Some rules are to be observed: EasyVision 1.0 User's Guide Page 61 If the identification code of the button matches a character in its name, that character will be highlighted. TAB/SHIFT-TAB and arrow keys codes cannot be used to identify a button. (9, 271, 328, 336, 331, 333) <sltext>: This is a short help text that will be displayed on the status line when the button is active. This arguement is optional. If it is not given, no help text will be displayed. {winsetslptr} must have been called. ■ Return None ■ Example window->buttoncreate (10,2," Save",'S',"Save file") ; EasyVision 1.0 User's Guide Page 62 TWINDOW::BUTTONPUSH ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Push a button. ■ Syntax #include "twindow.hpp" void buttonpush (int buttonkey) ; ■ Remarks <buttonkey> is the identification code (case insensitive) of the button you want to push. If the button doesn't exist, the function has no effect. Otherwise, the button is pushed in a 3D fashion. ■ Return None ■ Example window->buttonpush ('S') ; EasyVision 1.0 User's Guide Page 63 TWINDOW::BUTTONINPUT ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Makes user go trough the buttons with TAB/SHIFT-TAB. ■ Syntax #include "twindow.hpp" int buttoninput ([int inchar, int first, int tabexit]); ■ Remarks You must have created at least 1 button to call this function, and there must be at least one button available. <inchar>: The initial user input (ASCII code). This could come from some previous processing. For instance, the result of an input field. This argument is optional and will default to 0. <first> : Determines which button will first be made active during the input. 1 means the first created button, 0 means the last. This argument is optional and will default to 1. <tabexit>:0 means the user can't get out of the input by going past the first or last button with TAB or SHIFT-TAB. Instead the active button will wrap around. 1 means it can get out. This argument is optional and will default to 0. ■ Return The function returns an int. It is the identification code of the button that was pushed. If the function was permitted to exit (<tabexit> = 1), then it can also return the TAB or SHIFT-TAB code. TAB (9) means the user got past the last button, SHIFT-TAB (271) means he got past the first button. ■ Example inchar = window->buttoninput () ; // Can't return until // button is pressed EasyVision 1.0 User's Guide Page 64 TWINDOW::BUTTONSETAVAIL ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Sets the availability of a button. ■ Syntax #include "twindow.hpp" void buttonsetavail (int buttonkey, int state) ; ■ Remarks The button specified MUST exist. <buttonkey>: The identification code of the button that you want to change. <state> : 1 means this button is available. 0 means it is not. When a button is created with {buttoncreate}, its availability status is automatically set to 1. ■ Return None ■ Example window->buttonsetavail ('S',0) ; // Save button OFF EasyVision 1.0 User's Guide Page 65 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 9 EasyVision's demo program ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ I am a true believer in 'You learn faster by looking at examples'. So, I have included a demo program with EasyVision. This demo program is included in the archive under the name DEMO.CPP. The compiled version is available under EVISION.EXE. I have tried to use as many functions as possible in this short source code. It is fully commented and illustrate the working relationship between all those functions and classes. I really think that 90% of your questions can be answered by going through this demo program. You are invited to try some modifications of your own, and see the results. I'll say it again... You should really print all of this documentation for easier reading. It's always a good idea to have the docs nearby when everything seems to go wrong. The Demo Program ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ A couple of things are to be remembered from this demo source code: First, you should always use HUGE POINTERS in your code. You'll be on the safe side and avoid many problems. I have used a global variable for the general help text. You should put all texts and prompts in a separate ressource file. This will make it easy to update prompts or make an alternate language file. EasyVision won't prevent you from using 'printf' statements. However, you should work within the EasyVision boundaries and use the provided output functions. All classes come with built in default values. Often, only one call is needed to use them if the defaults are to your taste. Looking at this demo program, you can see that you can make great looking software faster than ever. Take the time to become familiar with EasyVision. The rewards will be less frustrations and more enjoyment out of your programming. Have fun ! Remy Gendron author of EasyVision EasyVision 1.0 User's Guide Page 66 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 10 Things you should not do ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Here are a couple of things I have found to be hasardeous to your health. I'd like to share them with you... Use this library without printing the manual. Use this library without looking at the example demo program. Use this library without registering ! Use printf statements. Use scanf statements. Instantiate more than one {tmenubar} object. Smoke. Use 3000 {winswrite} statements. Use {wintextfile} on really big text files. It's kindda slow. Using BC++ 3.0 on a slow computer. Using a function without reading its documentation twice. Make fun of your brother in law if he's a karate black belt. You should begin to get the idea... Be careful, that's all I ask... EasyVision 1.0 User's Guide Page 67 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ A P P E N D I X A Extended keycodes ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Extended keycodes are returned when you press a key that doesn't have an associated ASCII code. They are represented by stuffing 2 codes into the keyboard buffer. A 0 followed by an extended key keycode in the range 0 through 255. The EasyVision {getkey} function deals with these codes by returning values (int) in the range 0 through 511. The standard ASCII codes are returned unchanged (Guess why ?). Extended keycodes are added 256 to their real value for convenience, and are returned as a single number. Here they are... 259 NUL 271 Shift-TAB 272-281 Alt Q/W/E/R/T/Y/U/I/O/P 286-294 Alt A/S/D/F/G/H/J/K/L 300-306 Alt Z/X/C/V/B/N/M 315-324 F1 to F10 327 Home 328 Up arrow key 329 Page Up 331 Left arrow key 333 Right arrow key 335 End 336 Down arrow key 337 Page Down 338 Ins 339 Del 340-349 Shift-F1 to Shift-F10 350-359 Ctrl-F1 to Ctrl-F10 360-369 Alt-F1 to Alt-F10 370 Ctrl-Print Screen 371 Ctrl-Left arrow key 372 Ctrl-Right arrow key 373 Ctrl-End 374 Ctrl-Page Down 375 Ctrl-Home 376-387 Alt 1/2/3/4/5/6/7/8/9/0/-/= 388 Ctrl-Page Up 389 F11 390 F12 391 Shift-F11 392 Shift-F12 393 Ctrl-F11 394 Ctrl-F12 395 Alt-F11 396 Alt-F12 EasyVision 1.0 User's Guide Page 68 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ A P P E N D I X B Color Codes and Symbolic constants ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ When asked for a color argument, you must provide one of the following values. As an alternative, you can also use special MACROS, provided <conio.h> as been included. Available background colors: 0 BLACK 1 BLUE 2 GREEN 3 CYAN 4 RED 5 MAGENTA 6 BROWN 7 LIGHTGRAY Available foreground colors: 0 BLACK 8 DARKGRAY 1 BLUE 9 LIGHTBLUE 2 GREEN 10 LIGHTGREEN 3 CYAN 11 LIGHTCYAN 4 RED 12 LIGHTRED 5 MAGENTA 13 LIGHTMAGENTA 6 BROWN 14 YELLOW 7 LIGHTGRAY 15 WHITE EasyVision 1.0 User's Guide Page 69 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ A P P E N D I X C Trademarks ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Turbo vision from Borland DeskView from Quarterdeck EasyVision from TNG SOFT ENTERPRISES CXL from Mike Smedley EasyVision 1.0 User's Guide Page 70 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ A P P E N D I X D Common Questions and Answers ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ As this is the first release of this software, I don't have any questions or answers. Doesn't make for a big appendix D... I will gladly answer any questions relating to this software. I can be reach via the C++ FidoNet echomail conference. Address your message to 'Remy Gendron'. Don't make a mistake in the name because I don't read the echo. The name must be correct if I want to be alerted to your message. I will not send answers through Netmail. It costs something ! But the real reason is that it won't benefit anyone else. Any comments, bug reports or suggestions will be appreciated. STARFLEET COMMAND BBS (418) 525-6899/4740/6803 FidoNet: 1:240/1701 or TNG SOFT ENTERPRISES 2480 Ave de Vitre Quebec, Quebec Canada G1J 4A6 Thank you for using this software ! Remy Gendron Author of EasyVision